<html>
<head><meta charset="utf-8"><title>Generated code, include directives, and attributes · general · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/index.html">general</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html">Generated code, include directives, and attributes</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="182266930"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182266930" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Josh Triplett <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182266930">(Dec 01 2019 at 03:37)</a>:</h4>
<p>I'm trying to use a build script to generate some code. I've written the generated code into <code>$OUT_DIR/lib-generated.rs</code>, and <code>src/lib.rs</code> contains an include directive to include that. However, I ran into the issue that included files can't contain module doc comments or module-level directives like <code>#![no_std]</code>. Is there a well-known solution for that? What's the best way to generate a crate's source code from <code>build.rs</code>?</p>



<a name="182272348"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182272348" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182272348">(Dec 01 2019 at 06:40)</a>:</h4>
<p>you should be able to document the module from <a href="http://lib.rs" target="_blank" title="http://lib.rs">lib.rs</a></p>
<div class="codehilite"><pre><span></span><span class="sd">/// docs here</span>
<span class="k">pub</span><span class="w"> </span><span class="k">mod</span> <span class="nn">generated</span><span class="p">{</span><span class="w"></span>
<span class="n">include</span><span class="o">!</span><span class="p">(</span><span class="n">generated</span><span class="p">)</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>



<a name="182272354"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182272354" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182272354">(Dec 01 2019 at 06:40)</a>:</h4>
<p>as for other directives, i simply placed all of them into <a href="http://lib.rs" target="_blank" title="http://lib.rs">lib.rs</a></p>



<a name="182272411"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182272411" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182272411">(Dec 01 2019 at 06:42)</a>:</h4>
<p>also you could just totally prevent the inner module from being known and having to document it maybe</p>



<a name="182272415"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182272415" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182272415">(Dec 01 2019 at 06:42)</a>:</h4>
<p>depends on how important that module was for user understanding, but for ogl33 i just make it all appear in the crate root</p>



<a name="182292762"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182292762" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Josh Triplett <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182292762">(Dec 01 2019 at 17:19)</a>:</h4>
<p>The code generation wants to generate the documentation, too.</p>



<a name="182292812"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182292812" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Josh Triplett <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182292812">(Dec 01 2019 at 17:20)</a>:</h4>
<p>I'd rather not hardcode it.</p>



<a name="182292816"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182292816" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Josh Triplett <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182292816">(Dec 01 2019 at 17:20)</a>:</h4>
<p>Ditto the directives.</p>



<a name="182324411"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182324411" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> gnzlbg <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182324411">(Dec 02 2019 at 08:34)</a>:</h4>
<p>You can generate the documentation in an <code>.md</code> file, and include it.</p>



<a name="182324516"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182324516" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> gnzlbg <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182324516">(Dec 02 2019 at 08:36)</a>:</h4>
<p>The only documentation that you can't generate is "top-level" documentation for a module that has an <code>include!</code> from within that <code>include!</code>.</p>



<a name="182324567"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182324567" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> gnzlbg <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182324567">(Dec 02 2019 at 08:37)</a>:</h4>
<p>but you can have:</p>
<div class="codehilite"><pre><span></span><span class="cp">#![doc(include = </span><span class="s">&quot;generated_docs.md&quot;</span><span class="cp">)]</span><span class="w"></span>
<span class="n">include</span><span class="o">!</span><span class="p">(</span><span class="n">generated</span><span class="p">);</span><span class="w"></span>
</pre></div>



<a name="182327209"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182327209" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182327209">(Dec 02 2019 at 09:23)</a>:</h4>
<p>markdown is good</p>



<a name="182327580"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182327580" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182327580">(Dec 02 2019 at 09:28)</a>:</h4>
<p>also try this:</p>
<div class="codehilite"><pre><span></span><span class="c1">// lib.rs is something like this</span>
<span class="c1">// you make a private inner module</span>
<span class="c1">// and pub use the content</span>
<span class="c1">// the outside world doesn&#39;t generally see the intermediate level</span>
<span class="c1">// (it will show up in the full path of error messages)</span>

<span class="k">pub</span><span class="w"> </span><span class="k">use</span><span class="w"> </span><span class="n">priv_includer</span>::<span class="o">*</span><span class="p">;</span><span class="w"></span>
<span class="k">mod</span> <span class="nn">priv_includer</span><span class="p">{</span><span class="w"></span>
<span class="w">  </span><span class="n">include</span><span class="o">!</span><span class="p">(</span><span class="n">gen</span><span class="p">.</span><span class="n">rs</span><span class="p">)</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="c1">// gen.rs immediately creates a pub module</span>
<span class="c1">// you can stick doc on this module from the outside</span>
<span class="c1">// and the inside should support inner attributes</span>

<span class="sd">/// docs for the module you want seen</span>
<span class="k">pub</span><span class="w"> </span><span class="k">mod</span> <span class="nn">the_module_you_want_seen</span><span class="p">{</span><span class="w"></span>
<span class="w">  </span><span class="c1">//...</span>
<span class="p">}</span><span class="w"></span>
</pre></div>



<a name="182327629"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Generated%20code%2C%20include%20directives%2C%20and%20attributes/near/182327629" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Generated.20code.2C.20include.20directives.2C.20and.20attributes.html#182327629">(Dec 02 2019 at 09:29)</a>:</h4>
<p>the outside world sees it as <code>my_crate::the_module_you_want_seen</code></p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>